<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>OSSC: OSSC编码规范详述</title>

<link href="../../tabs.css" rel="stylesheet" type="text/css"/>
<link href="../../doxygen.css" rel="stylesheet" type="text/css" />
<link href="../../navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../jquery.js"></script>
<script type="text/javascript" src="../../resize.js"></script>
<script type="text/javascript" src="../../navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="../../search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>

</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  <td id="projectlogo"><img alt="Logo" src="../../OSSC-logo.png"/></td>
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">OSSC
   &#160;<span id="projectnumber">0.1.6</span>
   </div>
   <div id="projectbrief">Aliyun Open Storage Service C SDK</div>
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- 制作者 Doxygen 1.7.6.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "../../search",false,'搜索');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="../../index.html"><span>首页</span></a></li>
      <li><a href="../../modules.html"><span>模块</span></a></li>
      <li><a href="../../annotated.html"><span>数据结构</span></a></li>
      <li><a href="../../files.html"><span>文件</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="../../search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="搜索" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="../../search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('d0/d9d/_o_s_s_c__c_o_d_i_n_g__s_t_y_l_e.html','../../');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">OSSC编码规范详述 </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="编码规范的重要性"></a>
编码规范的重要性</h2>
<p>如前文所述，一个优秀的项目必须遵循良好的编码规范，良好的编码风格可以促进团队协作，减少 BUG 产生几率，有助于开发后的代码审查，降低后期维护成本。 </p>
<h2><a class="anchor" id="OSSC编码规范概述"></a>
OSSC编码规范概述</h2>
<ul>
<li>OSSC 所有函数名和类名（即结构名，下同）均已小写字符书写，全局枚举量，常量和宏定义在include/ossc/oss_constants.h中。</li>
</ul>
<ul>
<li>类名以 “oss_” 为前缀，并以 “_t” 为后缀，名字中间的单词（均为小写）用来标识该结构的用途，单词以下划线“_”连接，比如：包含终止一个Multipart上传事件的请求参数被命名为 oss_abort_multipart_upload_request_t，或者包含访问阿里云开放存储服务的入口“类”被命名为 oss_client_t，其他以此类推。</li>
</ul>
<ul>
<li>与各个类对应的函数均以函数指针的形式调用（除了oss_client_t, oss_client_t类相关的函数均以 "client_"为前缀，第一个参数是 oss_client_t 指针，比如client_create_bucket()），比如oss_abort_multipart_upload_request_t中设置 Bucket 名称可以按照如下方式调用， <div class="fragment"><pre class="fragment"> request-&gt;set_bucket_name(request，<span class="stringliteral">&quot;bucket-name-001&quot;</span>);
</pre></div> <dl class="note"><dt><b>注解:</b></dt><dd>调用规则：类（即结构，如前文所述）的指针调用其内部的函数指针所指向的函数，该函数的第一个参数是其自身结构的指针，第二个参数开始就是该函数真正的参数，注意，这与 C++ 或 Java 的调用习惯相似，只是第一个参数固定为指向自身结构的指针。</dd></dl>
</li>
<li>所有类对外均提供初始化函数和析构函数，其它与该类相关的操作均通过该类的函数指针调用，其中初始化函数命名规则为：该类的(BARE)类名（即类名去掉“oss_”前缀和“_t”后缀）+initialize， 析构函数为该类的(BARE)类名（即类名去掉“oss_”前缀和“_t”后缀）+finalize。</li>
</ul>
<ul>
<li>访问阿里云开放存储服务（Open Storage Service， OSS）的入口“类”是 oss_client_t，与此对应的所有函数均以client_前缀开头，并且第一个参数都是指向client结构的指针。 </li>
</ul>
<h2><a class="anchor" id="源码目录介绍"></a>
源码目录介绍</h2>
<p>OSSC 的源码目录如下： </p>
<div class="fragment"><pre class="fragment"> .
 ├── AUTHORS
 ├── build
 ├── CMakeLists.txt
 ├── config.h.cmake.in
 ├── doc
 ├── include
 ├── LICENSE.txt
 ├── README.txt
 ├── src
 ├── example
</pre></div><p>其中</p>
<ul>
<li>AUTHORS文件是作者（包括贡献者）的基本信息；</li>
</ul>
<ul>
<li>build 目录是构建目录，建议在该目录下构建 OSSC，实际上由于 OSSC 采用的是 CMake OUT-OF-SOURCE 构建方式，所以只能在该目录下编译 OSSC；</li>
</ul>
<ul>
<li>CMakeList.txt 是项目的顶级 CMake 脚本；</li>
</ul>
<ul>
<li>config.h.cmake.in 是 CMake 待检测的编译选项；</li>
</ul>
<ul>
<li>doc 目录包含了 OSSC 的所有文档；</li>
</ul>
<ul>
<li>include目录是包含了OSSC 所需的头文件；</li>
</ul>
<ul>
<li>LICENSE.txt 是OSSC的项目采用的开源条款；</li>
</ul>
<ul>
<li>README.txt是说明文档；</li>
</ul>
<ul>
<li>src是OSSC的全部源码；</li>
</ul>
<ul>
<li>example目录包含了一些 OSSC 的实际使用例子。</li>
</ul>
<h2><a class="anchor" id="命名规则"></a>
命名规则</h2>
<p>OSSC 完全采用C开发，遵循一套完整的命名规则，具体如下： </p>
<h3><a class="anchor" id="文件命名规则"></a>
文件命名规则</h3>
<p>OSSC 实现了面向对象的调用方式，类的所有函数均以函数指针的方式实现。所有文件名均以 oss_ 开头，其中各个类(结构)的头文件主要存放在 include/ossc/modules目录下面， 对应的实现文件则存放在 src/modules 目录中，另外每个类的头文件和实现文件命名规则为 "oss_" + 类名小写（单词间采用下划线 “_” 连接）， 比如 client 类（OSS 服务入口类）的实现文件是 src/moduels/oss_client.c，而对应的头文件则是 <a class="el" href="../../d0/df8/oss__client_8h.html">include/ossc/modules/oss_client.h</a>。</p>
<h3><a class="anchor" id="类名，函数名，变量名，常量名，宏等命名规则"></a>
类名，函数名，变量名，常量名，宏等命名规则</h3>
<ul>
<li>类名以 “oss_” 为前缀，并以 “_t” 为后缀（内部定义为 struct oss_class_name_s），名字中间的单词（均为小写）用来标识该结构的用途，单词以下划线“_”连接，如 client 类命名为 oss_client_t。</li>
</ul>
<ul>
<li>OSSC 函数分为内部使用函数和提供给外部接口函数两类，其中内部使用的函数使用下划线“_”开头，另外函数名也均以小写书写，单词间以下划线“_”连接， OSSC 提供外部使用的函数也分为两小类，一种是 helper 函数，即辅助函数，此类函数也以 "oss_" 开头，后面跟实际函数名，一般而言函数名尽量体现函数功能，如计算 md5 的函数 oss_compute_md5_digest()， 或者获取文件大小 oss_get_file_size()；另外一种是 core 函数，即 client类 （oss_client_t）的核心函数，此类函数均已 “cilent_”开头，其后名称也尽量体现该函数的功能， 比如下载 Object 至内存的函数是 <a class="el" href="../../d9/df5/group__oss__client__t.html#gadd5e0b9de089d3d40c9223559b15bd01" title="从 OSS 指定的 Bucket 中导出指定的 OSSObject 到内存">client_get_object_to_buffer()</a>，创建 Bucket 的函数名为 <a class="el" href="../../d9/df5/group__oss__client__t.html#ga0feb96409f1d8d499f6301ce1c730e23" title="创建 Bucket">client_create_bucket()</a>;</li>
</ul>
<ul>
<li>变量名均采用小写字母命名，单词间采用下划线连接“_”，可以合理缩写，但是应以准确易读为标准，对于无意义的循环变量，可以使用诸如 i, j, k类似的单个字母，但是并不推荐该方法。</li>
</ul>
<ul>
<li>常量名（const）以“k”开头，其余字母或单词均用大写，如 kMYVAR，kPAGESIZE等。</li>
</ul>
<ul>
<li>宏名均采用大写字母，一般以“OSS”开头，单词间以下划线“_“连接，如 OSS_HTTP_GET, OSS_CONTENT_TYPE。</li>
</ul>
<h3><a class="anchor" id="其他命名规则"></a>
其他命名规则</h3>
<p>其他命名规则比较宽泛，OSSC 不作严格要求。</p>
<h2><a class="anchor" id="排版"></a>
排版</h2>
<p>以下内容部分参考: </p>
<dl class="see"><dt><b>参见:</b></dt><dd><a href="https://innosoc.googlecode.com/files/%E7%BC%96%E7%A8%8B%E8%A7%84%E8%8C%83.pdf">https://innosoc.googlecode.com/files/%E7%BC%96%E7%A8%8B%E8%A7%84%E8%8C%83.pdf</a> </dd></dl>
<h3><a class="anchor" id="缩进与对齐"></a>
缩进与对齐</h3>
<p>缩进代码统一采用 4 格缩进,4 个空格或 Tab 字符,若采用 Tab 字符,应调整编辑器将 Tab 宽度设置为 4。另外，不要在代码中混合使用 Tab 和空格来进行缩进。 </p>
<h3><a class="anchor" id="放置花括号"></a>
放置花括号</h3>
<p>对于 if, for, while 等关键字，起始花括号放在该行的末尾，而对于函数的起始花括号则新起一行放置，如下面例子所示： </p>
<div class="fragment"><pre class="fragment"> <span class="keyword">static</span> <span class="keyword">inline</span> <span class="keywordtype">void</span>
 __bucket_set_name(
                <a class="code" href="../../db/db9/structoss__bucket__s.html" title="Bucket是OSS上的命名空间   Bucket名在整个 OSS 中具有全局唯一性,且不能修改； 存储在OSS上的每个Object必须都包含在某个Bucket中。 一个应用，例如图片分享网站，可以对应...">oss_bucket_t</a> *bucket,
                <span class="keyword">const</span> <span class="keywordtype">char</span> *name,
                <span class="keywordtype">size_t</span> name_len)
 {
        <span class="keywordflow">if</span> (bucket-&gt;<a class="code" href="../../db/db9/structoss__bucket__s.html#a5ac083a645d964373f022d03df4849c8" title="Bucket的名称">name</a> != NULL) {
                free(bucket-&gt;<a class="code" href="../../db/db9/structoss__bucket__s.html#a5ac083a645d964373f022d03df4849c8" title="Bucket的名称">name</a>);
                bucket-&gt;<a class="code" href="../../db/db9/structoss__bucket__s.html#a5ac083a645d964373f022d03df4849c8" title="Bucket的名称">name</a> = NULL;
        }
        bucket-&gt;<a class="code" href="../../db/db9/structoss__bucket__s.html#a5ac083a645d964373f022d03df4849c8" title="Bucket的名称">name</a> = (<span class="keywordtype">char</span> *)malloc(<span class="keyword">sizeof</span>(<span class="keywordtype">char</span>) * name_len + 1);
        strncpy(bucket-&gt;<a class="code" href="../../db/db9/structoss__bucket__s.html#a5ac083a645d964373f022d03df4849c8" title="Bucket的名称">name</a>, name, name_len);
        (bucket-&gt;<a class="code" href="../../db/db9/structoss__bucket__s.html#a5ac083a645d964373f022d03df4849c8" title="Bucket的名称">name</a>)[name_len] = <span class="charliteral">&#39;\0&#39;</span>;
 }
</pre></div> <h3><a class="anchor" id="空格"></a>
空格</h3>
<ul>
<li>双目运算符两侧,需要留有空格。如 “=”, “+=”,“&gt;=”, “&lt;=”, “+”, “&amp;&amp;”, “&lt;&lt;”, “^”等。</li>
</ul>
<ul>
<li>if, for, while, switch 等关键字之后,与紧接着的左括号‘(’之间,要留有一个空格。</li>
</ul>
<ul>
<li>左花括号“{”之前，右括号“)”与左花括号“{”之间要留一空格。</li>
</ul>
<ul>
<li>函数参数之间逗号‘,’分隔后面要留有空格。</li>
</ul>
<ul>
<li>for 语句分号‘;’分隔后面要留有空格。</li>
</ul>
<h3><a class="anchor" id="空行"></a>
空行</h3>
<ul>
<li>函数定义的前后,均需要适当的空行。</li>
</ul>
<ul>
<li>在函数体内,在一组变量定义完之后,需要适当空行。</li>
</ul>
<ul>
<li>一段逻辑性相关的代码前后需要加空行。</li>
</ul>
<h3><a class="anchor" id="代码行"></a>
代码行</h3>
<ul>
<li>一行代码宽度应不超过 80 个字符,对于较长的语句,应该分行书写,增加代码的可读性。</li>
</ul>
<h2><a class="anchor" id="注释"></a>
注释</h2>
<p>OSSC 采用 Doxygen 进行文档维护，具体注释风格与 JAVADOC 一致，参见 Doxygen 官方网站。</p>
<dl class="see"><dt><b>参见:</b></dt><dd><a href="http://www.stack.nl/~dimitri/doxygen/docblocks.html">http://www.stack.nl/~dimitri/doxygen/docblocks.html</a></dd></dl>
<p>另外，OSSC 头文件和实现文件开头均加上了如下语句： </p>
<div class="fragment"><pre class="fragment"> /\*
  * =============================================================================
  *
  *       Filename:  oss_part_listing.h
  *
  *    Description:  oss_part_listing.
  *
  *        Created:  09/04/2012 08:57:48 PM
  *
  *        Company:  ICT ( Institute Of Computing Technology, CAS )
  *
  *
  * =============================================================================
  *\/
</pre></div> </div></div><!-- contents -->
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>全部</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>数据结构</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>文件</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>函数</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>变量</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>类型定义</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>宏定义</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

  <div id="nav-path" class="navpath">
    <ul>
      <li class="navelem"><a class="el" href="../../index.html">OSSC 开发者手册</a>      </li>

    <li class="footer">Generated at 2012年十月30日 星期二 13:26:47 for OSSC by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.6.1 </li>
   </ul>
 </div>


</body>
</html>
